[0.9.0] Season seats: setAsideSeasonBlock, retrieveSeasonBlock, releaseSeasonBlock, inventoryMode - #14

Season seats for io.seatlayer:seatlayer-java, part of the 0.9.0 release. One release, 0.9.0, carries season 2a (#13) and this PR (decided 10 Nov).

• Versions: old 0.8.0 (published) → new 0.9.0 (with season-2a, Season 2a server operations (part A) #13). Nothing is published yet: Maven Central stops at 0.8.0 (maven-metadata.xml latest and release, checked 10 Nov).
• 0.8.0 has the 48 season operations from 0.7.0/0.8.0. It has none of the season-2a calls and none of these.
• The branch is cut from season-2a-server so it builds on the season-2a methods. Its name still says 0.10.0, from before the decision: renaming a head branch would close the PR.
• No version bump, tag or publish is in this PR. pom.xml is untouched. A tag push publishes all the way to Maven Central (autoPublish), and a Central version can never be replaced or deleted.

What it adds

Built to docs/season-block-2026-11-08/contract.md in the app repo (§2, §5, §6, and §8 "Amendments, 9 Nov"). Method names are the operationIds.

• Methods (the Map<String, Object> params style of the other season methods):

  • seasons.setAsideSeasonBlock(seasonKey, Map.of("expectedRevision", …, "keepForSingleTickets", …), idempotencyKey);
  • seasons.retrieveSeasonBlock(seasonKey);
  • seasons.releaseSeasonBlock(seasonKey, Map.of("expectedRevision", …, "scope", …, "eventKeys", …, "at", …, "reason", …), idempotencyKey).

  Both writes use header replay, so an Idempotency-Key is generated when the key is null, as on refundSeasonPerformance. Each write answers the job and the block; follow the job with retrieveSeasonBulkJob.

• inventoryMode (block | per_hold) on createSeason and updateSeason, documented on both and sent only when given. block opts the season into season seats; the default stays per_hold. Every Season answer carries it.

• The 202 while a date leaves every season seat (createSeasonAmendment cancel, markSeasonPerformancePast): Seasons.isDateLeavePending(answer). The return types are unchanged.

• Webhooks: Webhooks sends any event name, so season.block.ready and season.block.released need no change. The CHANGELOG names them.

• Errors: no new classes or constants. The new codes come through SeatLayerException and its subclasses with code() (§8 item 4). The CHANGELOG lists them, now including every code the 3 calls and inventoryMode can send (SEASON_BLOCK_API_BUSINESS_ERRORS in the app repo).

• Docs: a "Season seats" section at the end of the README's "Fixed Renewable Seasons": opt in with inventoryMode, set the seats aside, follow the job, read the block, release to single sale (now or at a set time), the two webhook names, the 202 guard, refusals through SeatLayerException with code(), and partner seats staying out of the block.

• CHANGELOG: the "Next: 0.9.0" section. The version PR joins it with the season-2a section under ## 0.9.0.

Files changed

CHANGELOG.md, README.md, src/main/java/io/seatlayer/Seasons.java, src/test/java/io/seatlayer/SeasonPlatformTest.java, src/test/java/io/seatlayer/SeasonTest.java (5 files, +309 −13).

Checks

• mvn -B verify (compile, tests, and the main/sources/javadoc jars under -Xdoclint:all,-missing with failOnError), re-run 10 Nov on this commit: green on Java 17, 90/90.
  • The operation map test goes 87 → 90: paths, exact bodies, the caller's key and the generated replay key.
  • A test sends the phase 4 answers through the transport: the 202s, a job of a new kind, and the 409 codes, each a SeatLayerConflictException with its code().
  • inventoryMode on create and update.
• Mutation check (run before this amend; the code is unchanged since): 7 mutants (the 3 paths, header replay, the caller's key, the guard's two halves): 7/7 killed.
• The README sample isn't compiled by the repo. It was compiled once (javac) against this commit's jar.
• Compat matrix: the same fixtures, shaped as the phase 4 API answers, through a stub transport, called by reflection so one program runs against every jar. The program is season-phase4-java-compat/Compat.java in the app session's notes; nothing is sent.

• Not done yet: a live dev smoke of the 3 calls with the dev test key. The phase 4 API isn't on dev until the stack merges; it is step 3 below.

Release steps for the owner

1. The season-2a PR (Season 2a server operations (part A) #13) merges to main, with no tag.
2. Rebase this PR onto main and retarget it to main; mvn -B verify green; merge.
3. Compat matrix again, once the phase 4 API is on dev:
   • run Compat.java against the Central 0.8.0 jar and against main's jar: both all PASS;
   • the live dev smoke of the 3 calls with the dev test key: opt in, set aside, follow the job to completed, read, release with at, read the release job.
4. Version PR: <version>0.9.0</version> in pom.xml (never a -SNAPSHOT), and join the CHANGELOG's season-2a section ("Unreleased") and "Next: 0.9.0" under a dated ## 0.9.0. Merge to main.
5. Publish: only after the phase 4 API (paiteq/seatmap #2059 → #2086 → #2061 → #2062 → #2063 → #2066 → #2092) is live on production and the owner says yes: git tag v0.9.0 && git push origin v0.9.0. release.yml runs mvn -B verify, refuses if the tag and the pom disagree, then signs and uploads to the Central Portal, which publishes automatically.
6. Live re-check:
   • https://repo1.maven.org/maven2/io/seatlayer/seatlayer-java/maven-metadata.xml reads 0.9.0 as <release>, and https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java lists it (allow some minutes for search);
   • in a scratch project, depend on io.seatlayer:seatlayer-java:0.9.0, then run the dev smoke from it.
7. Rollback (0.9.0 only adds): a Central version can't be deleted, and <release> can't be pointed back at 0.8.0. Publish nothing over it. Document the withdrawal in the CHANGELOG and the README, tell users to pin 0.8.0, and ship a fix as 0.9.1. A rollback also withdraws season-2a: both ship in 0.9.0.

Failure modes

• Publishing before the phase 4 API is on production: the 3 calls would answer 404, and inventoryMode would be ignored. Step 5 waits for production, and on Central that order matters most: a published 0.9.0 stays forever.
• A caller skipping Seasons.isDateLeavePending: it would read the 202 body as the amendment. The README and the Javadoc point at the guard.
• Old SDKs: 0.8.0 reads the new answers through its generic exception and ignores inventoryMode (compat matrix). It can't call the 3 new routes.
• README drift: the sample isn't compiled. A later signature change would leave it stale.

Open risks

• No live dev smoke yet (step 3).
• The README links to the docs' "Season seats" section (/server-api/seasons/#season-seats), which goes live with paiteq/seatmap #2063. Until then the link lands on the top of the Seasons page.
• The README's season intro still counts 87 operations (it is 90 with this PR); it was left as it was.